<html>
	<head>
		<!-- Update title -->
		<title>Documenting Cinder</title>

		<!-- keywords used for searching -->
		<meta name="keywords" content="guide, docs, documentation">

		<!-- reference to cinder classes -->
   		<!-- <ci seealso dox="[CLASS NAME GOES HERE]" label="[NAME OF LINK]"></ci> -->

   		<!-- master stylesheet - these links will be replaced when compiled -->
		<link rel="stylesheet" href="../../_assets/css/foundation.css">
		<link rel="stylesheet" href="../../_assets/css/prism.css">
		<link rel="stylesheet" href="../../_assets/css/style.css">
		<link href='http://fonts.googleapis.com/css?family=Open+Sans:400,300,600,700' rel='stylesheet' type='text/css'>

		<!-- Place additional stylsheet links here, which will be copied over when compiled (optional) -->
		<style type="text/css">
		.dynamic {
			color: #999;
		}
		</style>
		
	</head>

	<body id="guide-contents" class="language-cpp">

		<!-- //////////////////// CONTENT STARTS HERE //////////////////// -->

		<h1>Documenting Cinder</h1>
		
		<p>As an open source project, the Cinder community welcomes anyone interested in helping to document the library and/or write guides to help other developers progress their understanding of the library. There are many different ways to contribute to this documentation and this guide is meant to walk through those different avenues. You may want to take a look at the <a href='building_docs.html'>Building Docs guide</a> before reading this one.</p>

		<section>
			<a name="anatomy"></a>
			<h2>Documentation Anatomy</h2>

			<h3>The Docs Generation Process</h3>
			<p>Cinder documentation generation is a 2 step approach; </p>
			<ol>
				<li><strong>Exporting source code documentation</strong>
					<p>This step uses Doxygen to generate a series of XML files, one for each namespace, class, struct, and interface in the library and a master tag file (<em>cinder.tag</em>) which encapsulates the relationships between all of those files.</p>
				</li>
				<li><strong>HTML generation and integration with guides</strong>
					<p>The Cinder documentation framework includes a mechanism to add documentation to a class' specific documentation page, as well as a method to easily link to specific pages of the documentation from your HTML files. The integration happens via a Python script, <em>generateDocs.py</em>, that parses all of the information and exports an HTML directory, ready for consumption.</p>
				</li>
			</ol>
			
			<a name="file-structure"></a>
			<h3>Docs File Structure</h3>
			<p>This is a brief overview of the new <strong>docs/</strong> directory structure. Names in <span class="dynamic">gray</span> specify dynamically generated files and folders that you won't see unless you generate the docs.</p>
			<ul>
				<li><strong>doxygen/</strong> - for doxygen related files and configuration
					<ul>
						<li><strong><span class="dynamic">cinder.tag</span></strong> <em>(generated by Doxywizard)</em> - contains library source file data and relationships</li>
						<li><strong>Doxyfile</strong> - Export configuration for Doxygen/DoxyWizard</li>
					</ul>
				</li>
				<li><strong><span class="dynamic">html/</span></strong> <em>(generated by generateDocs.py)</em> - contains final HTML and asset files</li>
				<li><strong>htmlsrc/</strong> - contains all HTML source files, including CSS, JavaScript, Mustache templates, and images
					<ul>
						<li><strong>_assets/</strong> - contains all CSS, images, and JavaScript files used throughout the docs</li>
						<li><strong>_docs/</strong> - contains all supplemental class documentation</li>
						<li><strong>_templates/</strong> - Mustache/HTML templates used by the Python script to generate docs with</li>
						<li><strong>guides/</strong> - source files for all guides</li>
						<li><strong>index.html</strong> - markup for the index page</li>
						<li><strong>reference/</strong> - source files for reference pages</li>
					</ul>
				</li>
				<li><strong>libs/</strong> - Python libraries used by generateDocs.py</li>
				<li><strong>stylesrc/</strong> - contains style source files, including Stylus (which is the preprocessor of choice) source files and a gulp config file.</li>
				<li><strong><span class="dynamic">xml/</span></strong> <em>(generated by DoxyWizard)</em> - all of the files containing data for each source file documentation page.</li>
			</ul>

			
		</section>

		<section>
			<a name="source"></a>
			<h2>Documenting Source Code</h2>
			<p>All of the inline comments within the Cinder source code are turned into documentation in the Doxygen export step. For instance, if you open up a header file, you will commonly see block comments above each method that look like this.</p>

<pre><code>
[from Surface.h]
/** \brief Constructs asynchronously a Surface from an images located at \a path. The loaded Surface is returned in \a surface.
**/
</code></pre>

			or single line comments like this
<pre><code>
//! Returns the width of the Surface in pixels
</code></pre>

			<p>If you choose to contribute to the inline source documentation, a <a href="https://www.stack.nl/~dimitri/doxygen/manual/markdown.html" target="_blank">subset of doxygen markdown</a> is supported, including but not limited to:
			<ul>
				<li><a href="https://www.stack.nl/~dimitri/doxygen/manual/markdown.html#md_inlinelinks">Adding inine links</a>: <code>[The link text](http://example.net/)</code></li>
				<li><a href="https://www.stack.nl/~dimitri/doxygen/manual/markdown.html#mddox_code_blocks">Code Block Indentation</a></li>
				<li><a href="https://www.stack.nl/~dimitri/doxygen/manual/commands.html#cmda">\a &lt;word&gt; in italics</a></li>
				<li><a href="https://www.stack.nl/~dimitri/doxygen/manual/commands.html#cmdp">\p &lt;word&gt; for monospace font</a></li>
				<li><a href="https://www.stack.nl/~dimitri/doxygen/manual/commands.html#cmdsee">\see { references }</a></li>
			</ul>
			</p>

			<p>Note that not If you want to do anything complex, it's highly recommended that you instead contribute to external documentation, as described below.</p>
		</section>

		<section>
			<a name="external"></a>
			<h2>External Documentation</h2>
			<p>To write supplemental documentation and guides for the docs, there is a separate process. All external documentation is written in HTML and lives in the <em>htmlsrc/</em> directory. You can refer to the <a href="#file-structure">Docs File Structure</a> for specifics. Unless you are contributing to the overall documentation site markup, you will be mainly concerned with the <em>_docs</em> and <em>guides</em> directories. The <em>_docs</em> directory includes markup and additional assets for class descriptions, while the <em>guides</em> directory includes all of the <a href="../../guides/index.html">Cinder guides'</a> markup. Before we go into the specifics of writing each type of external docs, let's look at the <code>&lt;ci&gt;</code> tag.</p>
		</section>

		<section>
			<a name="citag"></a>
			<h2>The &lt;ci&gt; tag</h2>
			<p>To assist in bridging the gap between the Cinder source reference pages and the supplemental HTML markup, we've created a special <strong>&lt;ci&gt; tag</strong>. This tag is used to specify any content within the supplemental documentation HTML that needs to be linked into the source reference, as well as to provide a way for reference pages to link back to our guides.</p>

			<p>These are the use-cases for the <code>&lt;ci&gt;</code> tag:
			
			<h3>To generate a link into a source documentation page</h3>
			<p>When writing guides, you may frequently want to reference specific source code constructs, such as a class, namespace, function, or enum. Since the docs are dynamically generated it's prohibitive to worry about the specific linkage. The ci tag makes it easy to link to a specific source code reference entry.</p>

			<p>For example, if you were writing a guide for FBOs and you wanted to link to Cinder's gl::Fbo class, you could simply write:</p>

<pre><code class="language-markup">
An &lt;ci&gt;Fbo&lt;/ci&gt; represents an OpenGL Framebuffer Object.
</code></pre>
			<p>When the file is processed through the docs generation script, it will find and link a tag to the correct HTML file; it converts the Cinder-specific &lt;ci&gt; tag to a standard &lt;a&gt; tag, like so:</p>
<pre><code class="language-markup">
An &lt;a href=&quot;../../classcinder_1_1gl_1_1_fbo.html&quot;&gt;Fbo&lt;/a&gt; represents an OpenGL Framebuffer Object.
</code></pre>
			
			<p>When using the &lt;ci&gt; tag this way, you can either specifiy the target between the opening and closing tags like this:</p>
<pre><code class="language-markup">
&lt;ci&gt;Fbo&lt;/ci&gt;
</code></pre>
			<p>or if you want to link to it using a different label than the one given, you can use the <em>"dox"</em> attribute:</p>
<pre><code class="language-markup">
&lt;ci dox="Fbo"&gt;This is an Fbo&lt;/ci&gt;
</code></pre>

			<p>In some cases it may be necessary to avoid ambiguity by offering the fully qualified symbol name (including its namespace):</p>
<pre><code class="language-markup">
&lt;ci dox="ci::gl::Fbo"&gt;This is an Fbo&lt;/ci&gt;
</code></pre>
			<p>Take a look at <a href="../../ci_tag_test.html">this test file</a> to see a list of different combinations.</p>


			<h3>To add a description to a specific class, interface, or struct</h3>
			<p>To avoid polluting the Cinder library header files, you can write additional class descriptions in a separate HTML file and have it injected into the actual class' description. We do this by placing all of your content into a ci tag, giving it an attribute of <em>prefix</em> and setting the <em>dox</em> attribute to the class that you are documenting.</p>

<pre><code class="language-markup">
&lt;ci prefix dox=&quot;cinder::Fbo&quot;&gt;
	&lt;p&gt;FBOs are used for doing off-screen rendering ...&lt;/p&gt;
	&lt;!-- continue writing content here --&gt;
&lt;/ci&gt;
</code></pre>

			<h3>To link a guide to a specific class reference page</h3>
			<p>We've also made it easy to link your guides from relevant classes. For instance, the guide for <a href="../cinder-images/index.html">using images in Cinder</a> discusses gl::Textures, Surfaces, and Channels. To associate that guide to those specific class pages, all you need to do is add these ci tags with a <code>seealso</code> attribute to the HTML page head:</p>

<pre><code class="language-markup">
&lt;head&gt;
	...
	&lt;ci seealso dox=&quot;ci::Surface&quot; label=&quot;Images in Cinder&quot;&gt;&lt;/ci&gt;
	&lt;ci seealso dox=&quot;cinder::ChannelT&quot; label=&quot;Images in Cinder&quot;&gt;&lt;/ci&gt;
	&lt;ci seealso dox=&quot;cinder::gl::Texture2d&quot; label=&quot;Images in Cinder&quot;&gt;&lt;/ci&gt;
	...
&lt;/head&gt;
</code></pre>

			<p>If you want your guide to link from all classes in a namespace, you can simply specify the just the namespace. This is useful for broad guides pertaining to bigger topics, like audio.</p>
&lt;head&gt;
	...
	&lt;ci seealso dox=&quot;cinder::audio&quot; label=&quot;Audio in Cinder&quot;&gt;&lt;/ci&gt;
	...
&lt;/head&gt;
			
			<p>Once those specific class reference pages are generated, a link to the guide will appear in the class detail side bar under "Related Links".
			 <img class="shadow center" src="images/related_links.png" />
			</p>
			
		</section>

		<section>
			<a name="guides"></a>
			<h2>Writing Guides</h2>
			<p>To write a guide to be included in the Cinder documentation, follow these steps:</p>
			<ol>
				<li>Create a new directory within the <em>docs/htmlsrc/guides</em> directory. The name of the directory should be short and descriptive (ex: audio, mac-setup, cinder-blocks, etc).</li>
				<li>Create a new index.html file in your new directory and copy the content from the HTML file at <a href="../_start-here/start-here.html">_start-here/start-here.html</a>. The file includes all of the CSS and JavaScript linkages that are used in the generated HTML directory. This is not essential, but will give you an accurate preview of how your guide will look once integrated.</li>
				<li>Write your guide in HTML. You can include your own JavaScript and CSS if you'd like.</li>
				<li>If you have multiple pages, <a href="#config">create a config file</a>.</li>
				<li>Add meta keywords that can be used for searchability within the docs.</li>
				<li>Add any <code>&lt;ci&gt; seealso</code> tags to classes that may be relevant (This can also be part of the config for multiple pages).</li>
				<li>Make a GitHub pull request</li>
			</ol>

			
			<a name="config"></a>
			<h3>The config file</h3>
			<p>For your convenience, you can optionally include a config.json file for if your guide has multiple pages. This file allows you to specify the pages in your guide for subnavigation, specify meta keywords for every page in your guide, rather than specifying these for each individual page.</p>
			<p>This is an example taken from the Path2d guide:</p>
<pre><code class="language-javascript">
{
	"data":{
		// keywords for finding this guide via search
		"metadata":
		{	
			"keywords": ["path2d", "shape2d", "bezier", "curves", "path", "lines"]
		},
		// subnavigation for every page of the guide
		"subnav":[
			{
				"label": "Part 1",					// label for the subnav link
				"link": "part1.html"				// link for the subnav link
			},
			{
				"label": "Part 2",
				"link": "part2.html"
			},
			{
				"label": "Part 3",
				"link": "part3.html"
			}
		],
		"seealso":
		{
			"label": "Path2d Guide",				// label for the seealso link(s)
			"dox": ["ci::Path2d", "ci::Shape2d"]	// classes to be linked from
		}
	}
}
</code></pre>
		</section>

		<section>
			<a name="tips"></a>
			<h2>Helpful tips</h2>
			<h3>Using the <em>pre</em> tag when writing code blocks</h3>
			<p>For code blocks, we use the <a href="http://prismjs.com/">Prism</a> syntax highlighter. It allows you to style your code blocks based on their language. This is the proper markup for Cinder C++ code blocks:</p>
<pre><code class="language-markup">
&lt;pre&gt;&lt;code&gt;
	//... write some code here to be highlighted
&lt;/code&gt;&lt;/pre&gt;
</code></pre>

			<p>By default, C++ is the specified language for code blocks. If you want to override that, you can use one of the following supported language classes:</p>			
			<ul>
				<li><code>language-c++</code> <em>(default)</em></li>
				<li><code>language-markup</code> <em>For HTML and XML</em></li>
				<li><code>language-bash</code></li>
				<li><code>language-javascript</code> <em>For JavaScript and JSON</em></li>
				<li><code>language-python</code></li>
			</ul>
			<p>You can write inline HTML code by using the &lt;code&gt; tag by itself:</p>
<pre><code class="language-markup">
&lt;code&gt;gl::ScopedGlslProg&lt;/code&gt; is a scoped glsl shader.
</code></pre>
	
			<h3>Special CSS</h3>
			<p>In addition to any styles included in the <a href="http://foundation.zurb.com/docs/" target="_blank">Foundation 5 framework</a>, there are a few classes that may be commonly used when writing documentation, which can be found in <em>stylesrc/stylus/helpers.styl</em>:</p>
			<h4>Image helpers</h4>
			<ul>
				<li><code>.center</code> for centering images</li>
				<li><code>.shadow</code> for adding a consistent drop-shadow throughout the guides</li>
				<li><code>.rounded</code> for adding rounded corners to images (best for application windows)</li>
			</ul>

			<h3>Including WebGL</h3>
			<p>We encourage you to use whatever web technologies that will make your documentation as helpful as possible, including the use of WebGL. To do so, you should be able to write your WebGL sample entirely in a separate file and save in the same guide directory. Then you can embed your sample into an iFrame. All assets within the guide's directory will be copied over.</p>
			<p>This is all you have to do to embed a WebGL iFrame into your markup:</p>
<pre><code class="language-markup">
&lt;iframe src=&quot;cube.html&quot; width=&quot;640&quot; height=&quot;400&quot; frameborder=0&gt;&lt;/iframe&gt;
</code></pre>
			<p>Note: Due to file system security measures, WebGL samples that rely on asset loading will not show up when viewing your guide via the file system. You will have to spin up a local server to view it, which should be pretty common if you are writing WebGL in the first place.</p>
		</section>

		<section>
			<a name="generation"></a>
			<h2>Running the Generation Script</h2>
			<p>Generating all of the docs takes a few minutes, which can be a hassle when testing out a specific guide. Here are a few tips for running generateDocs.py</p>

			<p>Running the default script by default generates every page of the documentation. Run it like so:</p>
<pre><code class="language-bash">
python generateDocs.py
</code></pre>
			
			<p>You can run the generator on a specific file by passing the source file as the first argument:</p>
<pre><code class="language-bash">
python generateDocs.py htmlsrc/index.html
</code></pre>
	
			<p>To regenerate a specific directory of files (such as a suite of guides that live in the same directory), you can specify the directory that you want processed:</p>
<pre><code class="language-bash">
python generateDocs.py htmlsrc/guides/opengl/
</code></pre>

			<p>When generating a source file documentation page, by default, all of the html files will be generated so that the script can link up referenced pages. To skip over that step, you can use the <code>-s</code> flag.</p>
<pre><code class="language-bash">
python generateDocs.py xml/namespacecinder.xml -s
</code></pre>
			
			<p>By default, debug log messages are ignored. To view all logging messages, the <code>-d</code> flag can be useful for debgging errors:</p>
<pre><code class="language-markup">
python generateDocs.py -d
</code></pre>
		</section>
		
		<!-- //////////////////// END CONTENT //////////////////// -->

		<!-- Scripts -->
		<script src="../../_assets/js/prism.js" type="text/javascript"></script>
		<!-- Place additional scripts here (optional) -->
		<!-- <script type="text/javascript"></script> -->

	</body>
</html> 